<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_ProgressBar - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.progressbar.introduction.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.progressbar.introduction.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.progressbar.html">Zend_ProgressBar</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.progressbar.html">Zend_ProgressBar</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.queue.html">Zend_Queue</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.progressbar.introduction" class="section"><div class="info"><h1 class="title">Zend_ProgressBar</h1></div>
    

    <div class="section" id="zend.progressbar.whatisit"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            <span class="classname">Zend_ProgressBar</span> is a component to create and update
            progressbars in different environments. It consists of a single
            backend, which outputs the progress through one of the multiple
            adapters. On every update, it takes an absolute value and optionally
            a status message, and then calls the adapter with some precalculated
            values like percentage and estimated time left.
        </p>
    </div>

    <div class="section" id="zend.progressbar.basic"><div class="info"><h1 class="title">Basic Usage of Zend_Progressbar</h1></div>
        

        <p class="para">
            <span class="classname">Zend_ProgressBar</span> is quite easy in its usage. You
            simply create a new instance of <span class="classname">Zend_Progressbar</span>, defining a
            min- and a max-value, and choose an adapter to output the data. If
            you want to process a file, you would do something like:
        </p>

        <pre class="programlisting brush: php">
$progressBar = new Zend_ProgressBar($adapter, 0, $fileSize);

while (!feof($fp)) {
    // Do something

    $progressBar-&gt;update($currentByteCount);
}

$progressBar-&gt;finish();
</pre>


        <p class="para">
            In the first step, an instance of <span class="classname">Zend_ProgressBar</span> is
            created, with a specific adapter, a min-value of 0 and a max-value
            of the total filesize. Then a file is processed and in every loop
            the progressbar is updated with the current byte count. At the end
            of the loop, the progressbar status is set to finished.
        </p>

        <p class="para">
            You can also call the  <span class="methodname">update()</span> method of
            <span class="classname">Zend_ProgressBar</span> without arguments, which just
            recalculates ETA and notifies the adapter. This is useful when there
            is no data update but you want the progressbar to be updated.
        </p>
    </div>

    <div class="section" id="zend.progressbar.persistent"><div class="info"><h1 class="title">Persistent progress</h1></div>
        

        <p class="para">
            If you want the progressbar to be persistent over multiple requests,
            you can give the name of a session namespace as fourth argument
            to the constructor. In that case, the progressbar will not notify
            the adapter within the constructor, but only when you call
             <span class="methodname">update()</span> or  <span class="methodname">finish()</span>. Also the current
            value, the status text and the start time for ETA calculation will
            be fetched in the next request run again.
        </p>
    </div>

    <div class="section" id="zend.progressbar.adapters"><div class="info"><h1 class="title">Standard adapters</h1></div>
        

        <p class="para">
            <span class="classname">Zend_ProgressBar</span> comes with the following three adapters:

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <a href="zend.progressbar.introduction.html#zend.progressbar.adapter.console" class="link">Zend_ProgressBar_Adapter_Console</a>
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <a href="zend.progressbar.introduction.html#zend.progressbar.adapter.jspush" class="link">Zend_ProgressBar_Adapter_JsPush</a>
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <a href="zend.progressbar.introduction.html#zend.progressbar.adapter.jspull" class="link">Zend_ProgressBar_Adapter_JsPull</a>
                    </p>
                </li>
            </ul>
        </p>

        <div class="section" id="zend.progressbar.adapter.console"><div class="info"><h1 class="title">Zend_ProgressBar_Adapter_Console</h1></div>
    

    <p class="para">
        <span class="classname">Zend_ProgressBar_Adapter_Console</span> is a text-based adapter
        for terminals. It can automatically detect terminal widths but supports
        custom widths as well. You can define which elements are displayed with
        the progressbar and as well customize the order of them. You can also
        define the style of the progressbar itself.
    </p>

    <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Automatic console width recognition</b><br /></span>
        

        <p class="para">
            <code class="code">shell_exec</code> is required for this feature to work on
            *nix based systems. On windows, there is always a fixed terminal
            width of 80 character, so no recognition is required there.
        </p>
    </p></blockquote>

    <p class="para">
        You can set the adapter options either via the <code class="code">set*</code> methods
        or give an array or a <span class="classname">Zend_Config</span> instance with options as first
        parameter to the constructor. The available options are:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <code class="code">outputStream</code>: A different output-stream, if you don&#039;t
                want to stream to STDOUT. Can be any other stream like
                <code class="code">php://stderr</code> or a path to a file.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">width</code>: Either an integer or the <b><tt>AUTO</tt></b>
                constant of <span class="classname">Zend_Console_ProgressBar</span>.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">elements</code>: Either <b><tt>NULL</tt></b> for default
                or an array with at least one of the following constants
                of <span class="classname">Zend_Console_ProgressBar</span> as value:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <b><tt>ELEMENT_PERCENT</tt></b>: The current value in percent.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <b><tt>ELEMENT_BAR</tt></b>: The visual bar which display
                        the percentage.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <b><tt>ELEMENT_ETA</tt></b>: The automatic calculated ETA.
                        This element is firstly displayed after five seconds,
                        because in this time, it is not able to calculate
                        accurate results.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <b><tt>ELEMENT_TEXT</tt></b>: An optional status message
                        about the current process.
                    </p>
                </li>
            </ul>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">textWidth</code>: Width in characters of the
                <b><tt>ELEMENT_TEXT</tt></b> element. Default is 20.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">charset</code>: Charset of the
                <b><tt>ELEMENT_TEXT</tt></b> element. Default is utf-8.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">barLeftChar</code>: A string which is used left-hand
                of the indicator in the progressbar.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">barRightChar</code>: A string which is used right-hand
                of the indicator in the progressbar.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">barIndicatorChar</code>: A string which is used for
                the indicator in the progressbar. This one can be empty.
            </p>
        </li>
    </ul>
</div>
        <div class="section" id="zend.progressbar.adapter.jspush"><div class="info"><h1 class="title">Zend_ProgressBar_Adapter_JsPush</h1></div>
    

    <p class="para">
        <span class="classname">Zend_ProgressBar_Adapter_JsPush</span> is an adapter which let&#039;s
        you update a progressbar in a browser via Javascript Push. This means
        that no second connection is required to gather the status about a
        running process, but that the process itself sends its status directly
        to the browser.
    </p>

    <p class="para">
        You can set the adapter options either via the <code class="code">set*</code> methods
        or give an array or a <span class="classname">Zend_Config</span> instance with options as first
        parameter to the constructor. The available options are:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <code class="code">updateMethodName</code>: The javascript method which
                should be called on every update. Default value is
                <span class="classname">Zend_ProgressBar_Update</span>.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">finishMethodName</code>: The javascript method which
                should be called after finish status was set. Default value is
                <b><tt>NULL</tt></b>, which means nothing is done.
            </p>
        </li>
    </ul>

    <p class="para">
        The usage of this adapter is quite simple. First you create a progressbar
        in your browser, either with JavaScript or previously created with plain
        <acronym class="acronym">HTML</acronym>. Then you define the update method and optionally the finish method
        in JavaScript, both taking a json object as single argument. Then you
        call a webpage with the long-running process in a hidden
        <code class="code">iframe</code> or <code class="code">object</code> tag. While the process is
        running, the adapter will call the update method on every update with
        a json object, containing the following parameters:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <code class="code">current</code>: The current absolute value
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">max</code>: The max absolute value
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">percent</code>: The calculated percentage
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">timeTaken</code>: The time how long the process ran yet
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">timeRemaining</code>: The expected time for the process to finish
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <code class="code">text</code>: The optional status message, if given
            </p>
        </li>
    </ul>

    <div class="example" id="zend.progressbar-adapter.jspush.example"><div class="info"><p><b>Example #1 Basic example for the client-side stuff</b></p></div>
        

        <div class="example-contents"><p>
            This example illustrates a basic setup of <acronym class="acronym">HTML</acronym>,
            <acronym class="acronym">CSS</acronym> and JavaScript for the JsPush adapter
        </p></div>

        <pre class="programlisting brush: html">
&lt;div id=&quot;zend-progressbar-container&quot;&gt;
    &lt;div id=&quot;zend-progressbar-done&quot;&gt;&lt;/div&gt;
&lt;/div&gt;

&lt;iframe src=&quot;long-running-process.php&quot; id=&quot;long-running-process&quot;&gt;&lt;/iframe&gt;
</pre>


        <pre class="programlisting brush: css">
#long-running-process {
    position: absolute;
    left: -100px;
    top: -100px;

    width: 1px;
    height: 1px;
}

#zend-progressbar-container {
    width: 100px;
    height: 30px;

    border: 1px solid #000000;
    background-color: #ffffff;
}

#zend-progressbar-done {
    width: 0;
    height: 30px;

    background-color: #000000;
}
</pre>


        <pre class="programlisting brush: javascript">
function Zend_ProgressBar_Update(data)
{
    document.getElementById(&#039;zend-progressbar-done&#039;).style.width =
         data.percent + &#039;%&#039;;
}
</pre>


        <div class="example-contents"><p>
            This will create a simple container with a black border and a
            block which indicates the current process. You should not hide
            the <code class="code">iframe</code> or <code class="code">object</code> by <code class="code">display: none;</code>,
            as some browsers like Safari 2 will not load the actual content then.
        </p></div>

        <div class="example-contents"><p>
            Instead of creating your custom progressbar, you may want to use
            one of the available JavaScript libraries like Dojo, jQuery etc.
            For example, there are:
        </p></div>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    Dojo: <tt class="uri">http://dojotoolkit.org/reference-guide/dijit/ProgressBar.html</tt>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    jQuery: <tt class="uri">http://t.wits.sg/2008/06/20/jquery-progress-bar-11/</tt>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    MooTools: <tt class="uri">http://davidwalsh.name/dw-content/progress-bar.php</tt>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Prototype: <tt class="uri">http://livepipe.net/control/progressbar</tt>
                </p>
            </li>
        </ul>
    </div>

    <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Interval of updates</b><br /></span>
        

        <p class="para">
            You should take care of not sending too many updates, as every update
            has a min-size of 1kb. This is a requirement for the Safari browser
            to actually render and execute the function call. Internet Explorer
            has a similar limitation of 256 bytes.
        </p>
    </p></blockquote>
</div>
        <div class="section" id="zend.progressbar.adapter.jspull"><div class="info"><h1 class="title">Zend_ProgressBar_Adapter_JsPull</h1></div>
    

    <p class="para">
        <span class="classname">Zend_ProgressBar_Adapter_JsPull</span> is the opposite of jsPush,
        as it requires to pull for new updates, instead of pushing updates out
        to the browsers. Generally you should use the adapter with the
        persistence option of the <span class="classname">Zend_ProgressBar</span>. On notify,
        the adapter sends a <acronym class="acronym">JSON</acronym> string to the browser, which looks exactly
        like the <acronym class="acronym">JSON</acronym> string which is send by the jsPush adapter. The only
        difference is, that it contains an additional parameter,
        <span class="property">finished</span>, which is either <b><tt>FALSE</tt></b> when
         <span class="methodname">update()</span> is called or <b><tt>TRUE</tt></b>, when
         <span class="methodname">finish()</span> is called.
    </p>

    <p class="para">
        You can set the adapter options either via the  <span class="methodname">set*()</span> methods
        or give an array or a <span class="classname">Zend_Config</span> instance with options as first
        parameter to the constructor. The available options are:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <span class="property">exitAfterSend</span>: Exits the current request after the
                data were send to the browser. Default is <b><tt>TRUE</tt></b>.
            </p>
        </li>
    </ul>
</div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.progressbar.html">Zend_ProgressBar</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.progressbar.html">Zend_ProgressBar</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.queue.html">Zend_Queue</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.progressbar.html">Zend_ProgressBar</a></li>
  <li class="active"><a href="zend.progressbar.introduction.html">Zend_ProgressBar</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>